home *** CD-ROM | disk | FTP | other *** search
/ Collection of Tools & Utilities / Collection of Tools and Utilities.iso / basic / pbc22a.zip / LIB_BI.DOC < prev    next >
Text File  |  1992-06-24  |  25KB  |  547 lines

  1.      LIB_BI.DOC  Copyright (c) 1992  Daniel M. Smith, Jr.
  2.  
  3.               TOWARD LIBRARIES AND INCLUDE FILES
  4.  
  5.  
  6.  
  7. This document consists of a basic tutorial on BASIC include
  8. files and libraries. It is included with my libraries by the
  9. kind permission of the author. The text has been edited for
  10. consistency with my existing documentation and includes minor
  11. alterations where I considered them helpful.
  12.    -- Thomas G. Hanlin III
  13.  
  14. While the following might be considered mundane by experienced
  15. programmers, it's always nice to have a good foundation to
  16. begin building on.  With that in mind, the examples and
  17. discussion of topics will be in relatively layman terminology.
  18. To give you an excellent grasp of each idea presented, examples
  19. and step-by-step procedures will be given.  If you are using
  20. any version of QuickBASIC including QBX Professional
  21. Development System, the information presented here is
  22. applicable to all, although some versions may present specific
  23. problems regarding arguments and syntax. In fact, it is
  24. germaine to all higher level languages but specifically to the
  25. many forms of BASIC which is the language we are concerned
  26. about.
  27.  
  28. Many routines have been developed by programmers to accomplish
  29. tasks within the BASIC environment. Some are simple, yet others
  30. are extremely complex, possibly requiring memory allocation,
  31. etc. Since these routines are already available why waste time
  32. trying to re-invent the wheel so to speak; include the ones you
  33. require into your program with the $INCLUDE Metacommand (hardly
  34. layman language, so let's take time right now to find out about
  35. this special terminology).
  36.  
  37. Metacommands are special commands that are used to make your
  38. programs perform in a specific fashion. BASIC has three such
  39. commands; two ($DYNAMIC and $STATIC) which deal with allocation
  40. of dimensioned arrays and the $INCLUDE command which provides a
  41. means of incorporating external programs or routines into your
  42. programs. It specifically tells the compiler to stop processing
  43. the current program in favor of the program directed by the
  44. $INCLUDE Metacommand. When the included program ends, execution
  45. returns to the next line of the main program following the
  46. included routine.
  47.  
  48. We are only concerned here with $INCLUDE since it is the means
  49. by which all external routines are usually made a part of the
  50. main program. There is a specific syntax required with all
  51. metacommands that needs to be emphasized; most curious is that
  52. these commands are always preceded by REM or the apostrophe
  53. character. The following is the correct syntax for $INCLUDE:
  54.  
  55.    REM $INCLUDE: 'MyFile.BI'
  56.       or
  57.    ' $INCLUDE: 'MyFile.BI'
  58.  
  59. More than one metacommand can be placed on the same line as
  60. long as they are separated by white space. The other two
  61. metacommands don't require an argument, so no colon (delimiter)
  62. is required when using them. Note that the above argument is
  63. enclosed by single quotation marks (apostrophes).
  64.  
  65. What is a ".BI" file?  Nothing can be more frustrating than
  66. trying to figure out what constitutes an include file when you
  67. have never been near one before.  Forget trying to track it
  68. down in reference books!! Here it is in a nutshell and will
  69. save you a lot of time.
  70.  
  71. First, it doesn't have to have the ".BI" extension at all, but
  72. that's the common extension used for BASIC Include files.
  73. Second, no SUB or FUNCTION programming statements are permitted
  74. in the file; and Third, include files must be in ASCII format.
  75. A ".BI" file then is simply the declaration statements
  76. identifying the external subroutine or function that you want
  77. to be included into the main program. The following syntax is
  78. what you could expect to find in a typical ".BI" file. Let's
  79. call it 'WINDO.BI'.
  80.  
  81. The metacommand is:
  82.    REM $INCLUDE: 'WINDO.BI'
  83.  
  84. The contents of the file might be:
  85.  
  86.    DECLARE SUB Windo (TRow%, LCol%, BRow%, RCol%)
  87.    DECLARE SUB Colour (ForeGrd%, BackGrd%, Scrn%)
  88.    DECLARE SUB Border (Style%, Title$)
  89.    DECLARE SUB WritWin (FC%, BG%, Text$)
  90.    ' (etc)
  91.  
  92. The list could go on to include other windowing capabilities
  93. such as saving the screen the window pops up on, restoring the
  94. screen when the window is closed, etc.  Whatever the routine or
  95. function you wish to include in your program requires a
  96. definition statement similar to the above in the ".BI" file.
  97. The actual program defined is, of course, located in a library
  98. of subroutines; you are only telling the program to expect
  99. these particular subroutines to be called elsewhere in the
  100. program. If it were not for the ".BI" file and the declarations
  101. contained therein, when the program reached the call to the
  102. subroutine a "SUBPROGRAM NOT DEFINED" error message would be
  103. encountered. Every subroutine and function must be defined
  104. either at the beginning of the main module or in the ".BI" file
  105. if it is to be called during program execution.  I should also
  106. point out here that all arguments (ie., those within the
  107. parentheses in the examples above) must be established in your
  108. program before you make the call to the external subroutine.
  109. The % arguments require integers and $ arguments require
  110. strings.
  111.  
  112. Let's assume you have a key trapped that directs your program
  113. to a label called WIN. We would expect to find something like
  114. the following:
  115.  
  116.    WIN:
  117.       TRow% = 8: LCol% = 20: BRow% = 18: RCol% = 60
  118.       BackGrd% = 2: ForeGrd% = 15: Scrn% = 0
  119.       Style% = 1: Title$ = "TEST WINDOW"
  120.  
  121. Now that the parameters are established:
  122.  
  123.    Border Style%, Title$
  124.    Colour ForeGrd%, BackGrd%, Scrn%
  125.    Windo TRow%, LCol%, BRow%, RCol%
  126.  
  127. The parameters can be set when the function is used, for
  128. example:
  129.  
  130.    LOCATE 10, 25
  131.    WritWin 14, 4, "This is only a test!"
  132.  
  133. By the way, why use Colour instead of Color, or Windo instead
  134. of Window? Because COLOR and WINDOW are BASIC keywords! We
  135. can't use them, since they are already defined to mean
  136. something else. Sometimes you have to be careful with names.
  137.  
  138. Declaration is not required for GOSUB, since you never have to
  139. pass any arguments explicitly.  The GOSUB statement is kind of
  140. a specialized version of GOTO, not a subroutine in the sense
  141. that a SUB or FUNCTION is.
  142.  
  143. Hopefully, this will help you to a proper perspective of ".BI"
  144. files.
  145.  
  146. NOW!! Here comes the big one. We will step through this very
  147. slowly because libraries are the backbone of programming. Each
  148. time a programmer prepares a method to accomplish a certain
  149. job, it becomes candidate for retention, since the same routine
  150. might be required again (either by himself or other persons who
  151. program in the same language).  These routines are normally
  152. placed in libraries. It could be a small library, or, if many
  153. routines have been created, it could be quite large. The term
  154. "library" is very appropriate, because (like books) routines
  155. can be removed from programming libraries and used when you
  156. need them, but do not need to be kept in your program when you
  157. don't. Much work and research go into solving specific tasks or
  158. coming up with better and more efficient ways of doing a
  159. particular job. Making these great routines available to others
  160. makes programming so much easier because you won't have to
  161. waste time trying to come up with the same routine again. Just
  162. extract it from the provided library and place in a new library
  163. you are going to use. Very easily said, but it takes
  164. considerable doing. This is exactly what we are going to
  165. examine now.
  166.  
  167. We will step through the entire procedure for creating a new
  168. library exactly in the same order as you should every time you
  169. decide to use someone else's library routines. Please keep in
  170. mind that these instructions are given from a QuickBASIC
  171. viewpoint. With other versions of BASIC you will have to make
  172. substitutions or modifications in the syntax where required.
  173.  
  174. First you must decide which routines you are going to need from
  175. the library. Make a list of the names of each routine on paper
  176. leaving room on the right for additional information.  You will
  177. realize the advantage of doing this shortly.
  178.  
  179. Next, you must have a listing (.LST) file of the library to
  180. find ou